home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
HPAVC
/
HPAVC CD-ROM.iso
/
HLP2TPH.ZIP
/
HLP2TPH.DOC
next >
Wrap
Text File
|
1993-10-28
|
7KB
|
154 lines
HLP2TPH v. 1.0 - Convert TurboPower .HLP files to Borland .TPH files
Copyright (c) 1993, D.J. Murdoch. This program is *not* public domain;
see the license description below.
SYNTAX:
Syntax: HLP2TPH Infile[.HLP] [Outfile[.TPH]] [/Option]
Will convert the TurboPower POPHELP help file Infile to
Borland .TPH format (suitable for the version 7.0 IDE or
the Pascal THELP 3.0). By default, the filename of the
output file is the same as the input file, with extension
changed to .TPH.
Option: /F Toggle automatic wrapping. By default, HLP2TPH will
produce help files with most paragraphs automatically
wrapped to fit the display window. Paragraphs
containing lines starting with a blank stay fixed.
With this option, all paragraphs stay fixed with the
original line breaks.
DESCRIPTION:
TurboPower Software distributes the help compiler MAKEHELP and the
TSR help viewer POPHELP with several of their toolkits. (For
details on how to get them, see below.) The Borland Pascal 7.0 IDE
allows you to load multiple help files, but the file format is
different from the TurboPower format. I found that I wanted to
switch between the Borland help and the TurboPower help so
frequently that I wanted everything in a single viewer.
Unfortunately, Borland charges $50 for their Open Architecture
Handbook, which comes with their help compiler. I already had my
own code to produce Borland .TPH files (as part of my update to
TurboPower's SCANHELP program), so I decided it wouldn't be hard to
write a file convertor that went from binary format to binary
format. It wasn't, and HLP2TPH was born.
DETAILS:
There are several differences between the Turbopower and Borland
help files that HLP2TPH has to work around. First, Borland help
files are written to work in the resizable windows of the IDE, while
TurboPower help files have all the word wrapping done by the
compiler. I've found that most files work well with automatic
wrapping, but have provided the /F option to turn it off.
The automatic wrapping works like this: HLP2TPH scans the help file
a paragraph at a time. (It considers any group of non-blank lines
to be a paragraph.) If any line in the paragraph is indented from
the left margin, then the whole paragraph will be left in fixed
format. If not, HLP2TPH will allow the IDE to reformat the
paragraph to fit the current size of the window.
The wrapping isn't perfect; there are several topics in OPRO.HLP
with paragraphs that HLP2TPH won't recognize as fixed, for instance.
If this is a problem, the only remedy is to alter the source for
that screen to insert blanks at the start of some of the lines, and
to recompile the file using MAKEHELP and then convert it again.
Another difference between the help formats is the indexing
strategy. TurboPower help files have essentially two indices:
a short one that you're supposed to look at, and a hidden one that's
used for context searches. (Topics are put in the short index if
you don't specify !NOINDEX, and they're put in the long index if you
don't specify !NOSEARCH.) Borland help files have only one index,
which may be merged by the IDE with the indices from other files.
In case of a collision (two help screens with the same index entry),
POPHELP cycles among the various possibilities, whereas Borland's
IDE presents all choices in the index, with a subtitle used to
distinguish among them.
I've chosen to adopt the following strategy to deal with this. I
create Borland index entries for all topics in the hidden index, and
try to guess at subtitles that will be appropriate to distinguish
collisions. I also create an index topic, and name it according to
the output filename. For example, OPRO.TPH would get a topic called
"OPRO index", which contains all the entries in the .HLP file short
index.
The subtitle guessing algorithm is to use the first highlighted word
on the first line as the subtitle. In the OPRO.HLP help file, this
guessing algorithm almost always finds the appropriate subtitle. In
some topics, there's no highlighted word on the first line; in that
case, I give no subtitle, and the Borland IDE will fall back to the
default subtitle, the help file filename.
Another difference between the formats is that the TurboPower format
has 3 levels of highlighting, while the Borland format has only one,
and uses it to mark code examples for pasting. HLP2TPH translates
all TurboPower highlighting into the single Borland highlight
method. Nested highlighting will switch back to normal text.
Finally, the Borland format doesn't provide any way to enter control
characters, while the TurboPower format uses a ^F to mark the next
character as a literal. HLP2TPH will insert the literal character,
unless it's a special control character for the Borland help system
(^A, ^B, ^E, or #0). There's no way to get those characters to
appear in a help topic. Unprefixed control characters will always be
translated by prefixing a "^" symbol.
GETTING MAKEHELP:
TurboPower Software distributes MAKEHELP and POPHELP with their
Object Professional, B-Tree Filer and Async Professional toolkits.
(They also distribute a help compiler with Turbo Professional, but
it is not compatible with HLP2TPH.) For information on these,
contact them at
TurboPower Software
P.O. Box 49009
Colorado Springs, CO 80949-9009
719-260-6641 (voice, Monday-Friday 9AM-5PM)
719-260-7151 (fax)
Compuserve: 76004,2611
ACKNOWLEDGMENTS:
Thanks to Kim Kokkonen of TurboPower Software for helpful comments
on HLP2TPH. HLP2TPH is written in Borland Pascal 7.0, using the
Object Professional toolkit from Turbopower.
LICENSE:
This program is not public domain. It was created by and is
copyrighted by Duncan Murdoch.
You are licensed to use HLP2TPH at no charge. You are also licensed
to distribute it unchanged, provided you charge no more than
reasonable distribution costs, and in no case more than $10 (US). In
particular, without prior written permission you may not include it
in a CD ROM compilation if you charge more than $10 (US) for the
collection.
Source code to HLP2TPH is available for $25 (US dollars drawn on a
US bank, or Canadian dollars drawn on a Canadian bank). As an
additional benefit, if you order the source code I'll also send you
a disk containing other Turbo Pascal utilities that I've written.
Comments and orders should be sent to
Duncan Murdoch
337 Willingdon Ave.
Kingston, Ontario, Canada
K7L 4J3
Email addresses:
Compuserve: 71631,122
Internet: dmurdoch@mast.queensu.ca
Fidonet: DJ Murdoch at 1:249/99.5